---
id: basic_commands
title: Commands Reference
---

import { Cards, Card } from "nextra/components";
import {
  DeviceFloppyIcon,
  DownloadIcon,
  TrashIcon,
  TerminalIcon,
  GlobeIcon,
  ListIcon,
  EyeIcon,
  ArrowRightOnRectangleIcon,
  PlayIcon,
} from "@radix-ui/react-icons";

# Commands Reference

Complete reference for FVM commands to manage Flutter SDK versions efficiently.

## use

Sets a Flutter SDK version for the current project. Creates project configuration and ensures environment consistency.

```bash
fvm use [version] [options]
```

### Arguments

- `version` - Flutter SDK version, channel, or commit hash (optional)
  - If omitted, checks project configuration or prompts for selection
  - Examples: `3.19.0`, `stable`, `fa345b1`

### Options

- `-f, --force` - Bypasses Flutter project validation checks
- `-p, --pin` - Pins the latest release of a channel (not for master)
- `--flavor <name>`, `--env <name>` - Sets version for a specific project flavor
- `-s, --skip-setup` - Skips SDK setup after installation
- `--skip-pub-get` - Skips dependency resolution after switching

### Examples

```bash
# Set specific version
fvm use 3.19.0

# Pin latest stable release
fvm use stable --pin

# Set version for production flavor
fvm use 3.19.0 --flavor production

# Use a specific commit
fvm use fa345b1
```

### What happens

1. Downloads SDK if not cached
2. Creates `.fvm` directory with SDK symlink
3. Updates `.fvmrc` configuration
4. Configures IDE settings (VS Code)
5. Runs `flutter pub get` (unless skipped)

## install

Downloads and caches a Flutter SDK version for future use. **Runs setup by default to ensure SDK is ready to use.**

```bash
fvm install [version] [options]
```

### Arguments

- `version` - Flutter SDK version to install (optional)
  - If omitted, installs version from project configuration

### Options

- `-s, --setup` - Downloads SDK dependencies after install (default: true)
- `--no-setup` - Skip downloading SDK dependencies for faster caching
- `--skip-pub-get` - Skips dependency resolution

### Aliases

- `fvm i` - Short form

### Examples

```bash
# Install with setup (default behavior)
fvm install 3.19.0

# Skip setup for faster caching
fvm install 3.19.0 --no-setup

# Install from project config
fvm install
```

## list

Displays all installed Flutter SDK versions.

```bash
fvm list
```

### Aliases

- `fvm ls` - Short form

### Output

Shows all cached SDK versions with their installation paths.

## releases

Shows available Flutter SDK releases for installation.

```bash
fvm releases [options]
```

### Options

- `-c, --channel <name>` - Filter by channel: stable, beta, dev, all (default: stable)

### Examples

```bash
# Show stable releases
fvm releases

# Show beta channel releases
fvm releases --channel beta

# Show all releases
fvm releases --channel all
```

## remove

Removes Flutter SDK versions from cache.

```bash
fvm remove [version] [options]
```

### Arguments

- `version` - SDK version to remove (prompts if omitted)

### Options

- `-a, --all` - Removes all cached versions

### Examples

```bash
# Remove specific version
fvm remove 3.19.0

# Remove all versions
fvm remove --all
```

## global

Sets a default Flutter SDK version for the system.

```bash
fvm global [version]
```

### Arguments

- `version` - SDK version to set as global

### Options

- `-f, --force` - Bypasses SDK validation
- `-u, --unlink` - Removes global version setting

### Examples

```bash
# Set global version
fvm global 3.19.0

# Remove global version
fvm global --unlink
```

## spawn

Runs Flutter commands with a specific SDK version.

```bash
fvm spawn <version> <flutter_command> [args...]
```

### Arguments

- `version` - SDK version to use (required)
- `flutter_command` - Flutter command to execute
- `args` - Additional command arguments

### Examples

```bash
# Build with specific version
fvm spawn 3.19.0 build apk

# Run tests with different version
fvm spawn 3.16.0 test
```

## exec

Executes commands using the project's configured Flutter SDK.

```bash
fvm exec <command> [args...]
```

### Arguments

- `command` - Command to execute
- `args` - Command arguments

### Examples

```bash
# Run melos with project SDK
fvm exec melos bootstrap

# Execute custom script
fvm exec ./scripts/build.sh
```

## flutter

Runs Flutter commands using the project's configured SDK.

```bash
fvm flutter <command> [args...]
```

### Arguments

- `command` - Flutter command to run
- `args` - Command arguments

### Examples

```bash
# Common Flutter commands
fvm flutter doctor
fvm flutter build apk
fvm flutter test
fvm flutter run
```

### Note

Prevents `flutter upgrade` on release versions. Use channels for upgrades.

## dart

Runs Dart commands using the project's configured SDK.

```bash
fvm dart <command> [args...]
```

### Arguments

- `command` - Dart command to run
- `args` - Command arguments

### Examples

```bash
# Common Dart commands
fvm dart pub get
fvm dart analyze
fvm dart format .
fvm dart run build_runner build
```

## destroy

Removes the entire FVM cache and all installed versions.

```bash
fvm destroy [options]
```

### Options

- `-f, --force` - Bypasses confirmation prompt (use with caution)

### Examples

```bash
# Remove cache with confirmation prompt
fvm destroy

# Remove cache without confirmation (dangerous)
fvm destroy --force
```

### Warning

This action is irreversible and removes all cached Flutter SDKs.

## flavor

Executes Flutter commands using a flavor-specific SDK version.

```bash
fvm flavor <flavor> <flutter_command> [args...]
```

### Arguments

- `flavor` - Project flavor name
- `flutter_command` - Flutter command to execute
- `args` - Command arguments

### Examples

```bash
# Build with development flavor
fvm flavor development build apk

# Test with staging flavor
fvm flavor staging test
```

## fork

Manages Flutter fork aliases for custom repositories.

### Subcommands

#### fork add

Adds a fork alias for a custom Flutter repository.

```bash
fvm fork add <alias> <url>
```

**Arguments:**
- `alias` - Short name for the fork
- `url` - Git repository URL (must end with .git)

**Example:**
```bash
fvm fork add mycompany https://github.com/mycompany/flutter.git
```

#### fork remove

Removes a fork alias.

```bash
fvm fork remove <alias>
```

**Example:**
```bash
fvm fork remove mycompany
```

#### fork list

Shows all configured fork aliases.

```bash
fvm fork list
```

### Using forks

After adding a fork, use it with any version:

```bash
# Install fork version
fvm install mycompany/stable
fvm install mycompany/3.19.0

# Use fork version
fvm use mycompany/stable
```

## config

Manages global FVM settings.

```bash
fvm config [options]
```

### Options

- `--cache-path <path>` - Sets custom cache directory
- `--flutter-url <url>` - Sets Flutter repository URL
- `--use-git-cache` - Enables Git cache for faster installs (default: true)
- `--no-use-git-cache` - Disables Git cache
- `--git-cache-path <path>` - Sets Git cache directory
- `--update-check` - Enables FVM update notifications (default: true)
- `--no-update-check` - Disables update notifications

### Examples

```bash
# View current configuration
fvm config

# Set custom cache location
fvm config --cache-path ~/custom/flutter/cache

# Disable update checks
fvm config --no-update-check

# Use custom Flutter repository
fvm config --flutter-url https://github.com/mycompany/flutter.git
```

## doctor

Shows detailed FVM environment information and diagnostics.

```bash
fvm doctor
```

### Output includes

- Project configuration
- IDE integration status
- Environment details
- Path validation
- FVM version

Useful for troubleshooting configuration issues.

## api

Provides JSON output for integration with other tools.

### Common options

- `-c, --compress` - Outputs compact JSON

### Subcommands

#### api list

Returns cached Flutter versions as JSON.

```bash
fvm api list [options]
```

**Options:**
- `-s, --skip-size-calculation` - Skips cache size calculation

#### api releases

Returns available Flutter releases as JSON.

```bash
fvm api releases [options]
```

**Options:**
- `--limit <number>` - Limits results
- `--filter-channel <channel>` - Filters by channel (stable, beta, dev)

#### api context

Returns FVM environment information as JSON.

```bash
fvm api context
```

#### api project

Returns project configuration as JSON.

```bash
fvm api project [options]
```

**Options:**
- `-p, --path <path>` - Project directory path

### Examples

```bash
# Get cached versions
fvm api list

# Get stable releases (limit 10)
fvm api releases --filter-channel stable --limit 10

# Get project info for specific path
fvm api project --path /projects/myapp

# Get compact JSON output
fvm api context --compress
```

## Command routing

When using proxy commands (`flutter`, `dart`, `exec`), FVM searches for the SDK in this order:

1. Project configuration
2. Ancestor directory configuration
3. Global FVM setting
4. System PATH

This ensures the correct SDK version is always used.